/**
 * @copyright Copyright (c) 2025 CSG Digital Grid Technology (Guangdong) Co., Ltd.
 * @author Xie Jinhui
 */

#ifndef APP_ACTION_H
#define APP_ACTION_H

/* 
 * Include standard integer type definitions for fixed-width integer types
 * Provides uint8_t, int32_t, etc. for platform-independent integer sizes
 */
#include <stdint.h>

/* 
 * Include POSIX operating system API for system calls
 * Provides access to POSIX-compliant system functions like file I/O and process control
 */
#include <unistd.h>

/* 
 * Include signal handling definitions
 * Provides signal types and functions for process signal management and handling
 */
#include <signal.h>

/* 
 * Define maximum length for command string buffers
 * Limits the size of command strings to prevent buffer overflow issues
 */
#define CMD_MAX_STRING_LEN 128

/* 
 * Define maximum length for execution message buffers
 * Sets the maximum size for messages returned by execution functions
 */
#define EXEC_MES_BUFF_LEN 256

/* 
 * Enumeration defining all possible execution result codes
 * Comprehensive set of return codes for application management operations
 * Includes success codes, error codes, and informational status codes
 */
typedef enum {
    /* 
     * Success code indicating operation completed without errors
     * Used when all requested operations execute successfully
     */
    INFO_NO_ERROR = 0,
    
    /* 
     * Error code for missing required command line arguments
     * Returned when mandatory parameters are not provided by user
     */
    ERROR_ARGUMENT_MISSING,
    
    /* 
     * Error code indicating target program is already running
     * Prevents multiple instances of the same application from running concurrently
     */
    ERROR_PROFRAAM_RUNNING,
    
    /* 
     * Informational code indicating help information was requested
     * Used when user requests command usage information with help flag
     */
    INFO_ARGE_HELP,
    
    /* 
     * Error code for input strings exceeding maximum allowed length
     * Prevents buffer overflow by rejecting overly long string inputs
     */
    ERROR_STRING_SUPER_LONG,
    
    /* 
     * General error code for invalid command line arguments
     * Catch-all for various argument parsing and validation failures
     */
    ERROR_ARGE_ERROR,
    
    /* 
     * Informational code indicating version information was requested
     * Used when user requests program version information
     */
    INFO_VERSION,
    
    /* 
     * Error code for malformed command line arguments
     * Specifically for syntax errors in argument formatting
     */
    ERROR_ARGS_ERR,
    
    /* 
     * Error code when specified application name does not exist in system
     * Returned when trying to operate on non-existent application
     */
    ERROR_ARGS_APPNAME_NOT_EXIST_ERR,
    
    /* 
     * Error code when specified package file path does not exist
     * Validates that package files are accessible at provided paths
     */
    ERROR_ARGS_PACKFILEPATH_NOT_EXIST_ERR,
    
    /* 
     * Error code for failures in converting relative paths to absolute paths
     * Used when path resolution functions fail to determine absolute path
     */
    ERROR_GET_ABSOLUTE_PATH_ERR,
    
    /* 
     * Error code when referenced software package does not exist
     * Different from path errors - package exists but is invalid or corrupted
     */
    ERROR_PACKAGE_NO_EXIST_ERR,
    
    /* 
     * Error code for authentication and authorization failures
     * Used when user lacks permissions or credentials for requested operation
     */
    ERROR_AUTHERNTIFICATION_FAIL,
    
    /* 
     * Error code for digital signature verification failures
     * Ensures package integrity and authenticity through cryptographic signatures
     */
    ERROR_FILE_SIGNATURE_ERR,
    
    /* 
     * Error code when required system or configuration files are missing
     * General file existence check failure for various operational files
     */
    ERROR_FILE_NOT_EXIT,
    
    /* 
     * Error code for application manager service failures
     * Indicates problems with the underlying application management subsystem
     */
    ERROR_INSTALL_APPMANGE_ERR,
    
    /* 
     * Error code for message token parsing and validation failures
     * Used in inter-process communication and message authentication
     */
    ERROR_SUB_MESSAGE_TOKEN_ERR,
    
    /* 
     * General error code for command execution failures
     * Catch-all for various runtime execution problems
     */
    ERROR_EXCUTE_ERR,
    
    /* 
     * Error code when target application does not exist in system registry
     * Application registry lookup failure for management operations
     */
    ERROR_APP_NOT_EXIT,
    
    /* 
     * Error code for application uninstallation failures
     * Specific to problems during application removal process
     */
    ERROR_APP_UNINSTALL_ERR,
    
    /* 
     * Error code for application startup failures
     * Used when application fails to launch or initialize properly
     */
    ERROR_APP_START_ERR,
    
    /* 
     * Error code for application termination failures
     * Used when application cannot be stopped gracefully or forcibly
     */
    ERROR_APP_STOP_ERR,
    
    /* 
     * Error code for application control command failures
     * General control interface failures for application management
     */
    ERROR_APP_CONTROL_ERR,
    
    /* 
     * Error code for application listing operation failures
     * Used when unable to retrieve or display installed applications
     */
    ERROR_APP_APP_LIST_ERR,
    
    /* 
     * Error code for JSON parsing and syntax errors
     * Used when configuration or message JSON cannot be parsed correctly
     */
    ERROR_JSON_PARSE_ERR,
    
    /* 
     * Error code for JSON message content validation failures
     * Used when JSON structure is valid but content is malformed or incomplete
     */
    ERROR_JSON_MESSAGE_INFO_ERR,
    
    /* 
     * Error code for application status retrieval failures
     * Used when unable to determine current state of application
     */
    ERROR_APP_APP_STATUS_ERR,
    
    /* 
     * Error code for application rights and permission failures
     * Used when security policies prevent requested operations
     */
    ERROR_APP_APP_RIGHTS_ERR,
    
    /* 
     * Error code for package naming convention violations
     * Validates package naming according to system requirements
     */
    ERROR_APP_PACK_NAME_ERR,
    
    /* 
     * Error code for temporary directory creation failures
     * Used during installation when temporary workspace cannot be created
     */
    ERROR_CREATE_APPINSTALL_TMPDIR_ERR,
    
    /* 
     * Error code for package file copy operation failures
     * Used when moving package files to installation directory fails
     */
    ERROR_CP_APP_PACK_TO_TARGET_DIR_ERROR,
    
    /* 
     * Error code for package file content examination failures
     * Used when package inspection or validation operations fail
     */
    ERROR_CAT_APP_PACK_ERROR,
    
    /* 
     * Error code for package archive extraction failures
     * Used when decompressing or unpacking application packages fails
     */
    ERROR_PACKAGE_DECOMPRESS_ERR,
    
    /* 
     * Error code for application file permission and ownership changes
     * Used when setting file permissions or ownership during installation fails
     */
    ERROR_CHAER_APP_FILE_ERROR,
    
    /* 
     * Error code for application profile access failures
     * Used when application configuration files cannot be opened or read
     */
    ERROR_OPEN_APPPROFILE_CTL_ERROR,
    
    /* 
     * Error code for application name extraction failures from profiles
     * Used when application name cannot be determined from configuration
     */
    ERROR_APPPROFILE_GET_APPNAME_ERROR,
    
    /* 
     * Error code for application name mismatch between command and package
     * Validates consistency between requested operation and package contents
     */
    ERROR_APPNAME_MISMATCHING,
    
    /* 
     * Maximum error code value for boundary checking
     * Used for validation and array sizing of error code arrays
     */
    ERROR_MAX
} EXEC_RESULE_CODE;

/* 
 * Main application action structure containing all operation parameters
 * Comprehensive structure holding application management command data
 * Includes operation flags, application identifiers, and file paths
 */
struct app_action{
    /* 
     * Buffer for storing application name string
     * Holds the name of the target application for management operations
     */
    char app_name[CMD_MAX_STRING_LEN];
    
    /* 
     * Buffer for storing package file path string
     * Contains filesystem path to application package for installation
     */
    char package_path[CMD_MAX_STRING_LEN];
    
    /* 
     * Buffer for storing default package path string
     * Contains default installation path when no specific path provided
     */
    char default_package[CMD_MAX_STRING_LEN];
    
    /* 
     * Flag indicating install operation requested
     * Boolean flag set when application installation is commanded
     */
    char set_install;
    
    /* 
     * Flag indicating uninstall operation requested
     * Boolean flag set when application removal is commanded
     */
    char set_uninstall;
    
    /* 
     * Flag indicating start operation requested
     * Boolean flag set when application launch is commanded
     */
    char set_start;
    
    /* 
     * Flag indicating stop operation requested
     * Boolean flag set when application termination is commanded
     */
    char set_stop;
    
    /* 
     * Flag indicating get information operation requested
     * Boolean flag set when application information retrieval is commanded
     */
    char set_getinfo;
    
    /* 
     * Flag indicating application name parameter provided
     * Boolean flag set when application name is specified in command
     */
    char set_appnane;
    
    /* 
     * Flag indicating file path parameter provided
     * Boolean flag set when package file path is specified in command
     */
    char set_filepath;
    
    /* 
     * Flag indicating default path should be used
     * Boolean flag set when default installation path should be utilized
     */
    char set_defaultpath;
    
    /* 
     * Flag indicating list operation requested
     * Boolean flag set when application listing is commanded
     */
    char set_list;
    
    /* 
     * Flag indicating version information output requested
     * Boolean flag set when program version display is commanded
     */
    char set_out_version;
};

/* 
 * Function to retrieve human-readable error message for result codes
 * Converts numeric error codes into descriptive text messages for user display
 * Provides internationalization support for error message reporting
 */
const char* get_error_message(EXEC_RESULE_CODE code);

/* 
 * Main command execution function for processing application management commands
 * Parses command line arguments and dispatches to appropriate handler functions
 * Implements the core command processing logic for the application manager
 */
char exec_option_command(int argc, char **argv);

/* 
 * Function for logging command execution results and operations
 * Records operational details and outcomes for auditing and debugging purposes
 * Supports system administration and troubleshooting activities
 */
void log_record(int ret,char *cmd);

/* 
 * Function to check if a specified program is currently running
 * Uses process table examination to determine program execution status
 * Supports prevention of multiple instances and conflict detection
 */
int is_program_running(const char *program_name);

#endif // APP_ACTION_H